home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / libdl / sgidladd.z / sgidladd
Encoding:
Text File  |  1998-10-30  |  13.4 KB  |  199 lines
  1.  
  2.  
  3.  
  4. SSSSGGGGIIIIDDDDLLLLAAAADDDDDDDD((((3333CCCC))))                                                      SSSSGGGGIIIIDDDDLLLLAAAADDDDDDDD((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ssssggggiiiiddddllllaaaadddddddd - open a shared object and add its variables to the name space.
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      cccccccc [ffffllllaaaagggg ...] ffffiiiilllleeee ...  ----llllcccc [lllliiiibbbbrrrraaaarrrryyyy ...]
  13.  
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddllllffffccccnnnn....hhhh>>>>
  15.  
  16.      vvvvooooiiiidddd ****ssssggggiiiiddddllllaaaadddddddd((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ppppaaaatttthhhhnnnnaaaammmmeeee,,,, iiiinnnntttt mmmmooooddddeeee))));;;;
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      ssssggggiiiiddddllllaaaadddddddd is a facility for dynamically loading shared objects.  Unlike
  20.      ddddllllooooppppeeeennnn(3)(without RRRRTTTTLLLLDDDD____GGGGLLLLOOOOBBBBAAAALLLL), the shared object loaded (and all it's
  21.      dependent shared objects), are added to the list of shared objects just
  22.      as if they had been specified at the time the program had been linked, or
  23.      as if the _RLD_LIST (see rrrrlllldddd(1)) envariable had been used.  That is to
  24.      say, all the names in the shared object become available to satisfy
  25.      references in shared objects during lazy text resolution (the DSOs are
  26.      globally visible: see also ddddllllooooppppeeeennnn "NAMESPACE ISSUES").
  27.  
  28.      _m_o_d_e may be any one of RRRRTTTTLLLLDDDD____LLLLAAAAZZZZYYYY, RRRRTTTTLLLLDDDD____NNNNOOOOWWWW, or RRRRTTTTLLLLDDDD____NNNNOOOOWWWW____RRRREEEEPPPPOOOORRRRTTTT____EEEERRRRRRRROOOORRRR.
  29.  
  30.      The mode RRRRTTTTLLLLDDDD____NNNNOOOOWWWW does exactly the same thing as RRRRTTTTLLLLDDDD____LLLLAAAAZZZZYYYY.  When the
  31.      mode is specified as RRRRTTTTLLLLDDDD____LLLLAAAAZZZZYYYY or RRRRTTTTLLLLDDDD____NNNNOOOOWWWW, resolution of all symbols is
  32.      performed, so that references which were previously unbound or bound to
  33.      weak symbols can be rebound to strong symbols. However, unresolvable
  34.      references (a reference to a symbol which does not exist in any shared
  35.      object or in the mainline) to functions are left dangling for further
  36.      "lazy" resolution, pending another call to ssssggggiiiiddddllllaaaadddddddd perhaps.
  37.  
  38.      When the mode is specified as RRRRTTTTLLLLDDDD____NNNNOOOOWWWW____RRRREEEEPPPPOOOORRRRTTTT____EEEERRRRRRRROOOORRRR resolution of all
  39.      symbols is performed, and any unresolvable reference  results in an error
  40.      return from ssssggggiiiiddddllllaaaadddddddd.  In this case, it is very dangerous to continue
  41.      execution, since resolution was not completed.  The main use for this
  42.      function is to ensure that at the point of the ssssggggiiiiddddllllaaaadddddddd, all symbols have
  43.      now been resolved. This is useful for verifying completeness of
  44.      interfaces.
  45.  
  46.      As with ddddllllooooppppeeeennnn, a handle to the added object is returned, and this handle
  47.      may be used to obtain addresses of specific symbols within the added
  48.      object. This is somewhat less useful than with ddddllllooooppppeeeennnn(without
  49.      RTLD_GLOBAL), since in the case of ssssggggiiiiddddllllaaaadddddddd rrrrlllldddd can resolve these symbols
  50.      directly (as can ddddllllooooppppeeeennnn with RTLD_GLOBAL).
  51.  
  52.      ssssggggiiiiddddllllaaaadddddddd is available in a library which is loaded if the option ----llllcccc is
  53.      used with cccccccc , ffff77777777 , or lllldddd.
  54.  
  55. SSSSEEEEAAAARRRRCCCCHHHHIIIINNNNGGGG FFFFOOOORRRR SSSSHHHHAAAARRRREEEEDDDD OOOOBBBBJJJJEEEECCCCTTTTSSSS
  56.      If other shared objects were link edited with _p_a_t_h_n_a_m_e when _p_a_t_h_n_a_m_e was
  57.      built, those objects are automatically loaded by ddddllllooooppppeeeennnn.  The directory
  58.      search path used to find both _p_a_t_h_n_a_m_e and the other _n_e_e_d_e_d objects is
  59.      the same as that used by rrrrlllldddd(1). In particular, _p_a_t_h_n_a_m_e is searched for
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSGGGGIIIIDDDDLLLLAAAADDDDDDDD((((3333CCCC))))                                                      SSSSGGGGIIIIDDDDLLLLAAAADDDDDDDD((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      in
  75.  
  76.      1) the directory specified by _p_a_t_h_n_a_m_e if it is not a simple file name
  77.      (_i._e.  it contains a //// character).  In this case, the exact file is the
  78.      only placed searched; steps two through four below are ignored.
  79.  
  80.      2) any path specified via the ----rrrrppppaaaatttthhhh argument to lllldddd(1) when the
  81.      executable was statically linked.
  82.  
  83.      3) any directory specified by the environment variable LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH.
  84.      This environment variable should contain a colon-separated list of
  85.      directories, in the same format as the PPPPAAAATTTTHHHH variable [see sssshhhh(1)].  64-bit
  86.      programs examine the variable LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY66664444____PPPPAAAATTTTHHHH and if it is not set
  87.      examine LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH.  New 32-bit ABI programs examine the variable
  88.      LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYYNNNN33332222____PPPPAAAATTTTHHHH and if it is not set examine LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH to
  89.      determine if an ABI-specific path has been specified.
  90.  
  91.      All three of these variables are ignored if the process is running sssseeeettttuuuuiiiidddd
  92.      or sssseeeettttggggiiiidddd [see eeeexxxxeeeecccc(2)].
  93.  
  94.      4) the default search paths are used.  These are ////uuuussssrrrr////lllliiiibbbb::::////lllliiiibbbb for 32-bit
  95.      programs, ////uuuussssrrrr////lllliiiibbbb66664444::::////lllliiiibbbb66664444 for 64-bit programs, and ////uuuussssrrrr////lllliiiibbbb33332222::::////lllliiiibbbb33332222
  96.      for new 32-bit ABI programs.
  97.  
  98.      The variable ____RRRRLLLLDDDD____RRRROOOOOOOOTTTT has its usual effect, as documented in the manpage
  99.      for rrrrlllldddd(1) (which means that for a sssseeeettttuuuuiiiidddd or sssseeeettttggggiiiidddd program _RLD_ROOT is
  100.      ignored).
  101.  
  102.       Objects whose names resolve to the same absolute or relative path name
  103.      may be opened any number of times using ssssggggiiiiddddllllaaaadddddddd, however, the object
  104.      referenced is only loaded once into the address space of the current
  105.      process.  The same object referenced by two different path names,
  106.      however, may be loaded multiple times.  For example, given the object
  107.      ////uuuussssrrrr////hhhhoooommmmeeee////mmmmeeee////mmmmyyyylllliiiibbbbssss////mmmmyyyylllliiiibbbb....ssssoooo, and assuming the current working directory
  108.      is ////uuuussssrrrr////hhhhoooommmmeeee////mmmmeeee////wwwwoooorrrrkkkkddddiiiirrrr,
  109.  
  110.           ............
  111.           vvvvooooiiiidddd ****hhhhaaaannnnddddlllleeee1111;;;;
  112.           vvvvooooiiiidddd ****hhhhaaaannnnddddlllleeee2222;;;;
  113.  
  114.           hhhhaaaannnnddddlllleeee1111 ==== ssssggggiiiiddddllllaaaadddddddd((((""""........////mmmmyyyylllliiiibbbbssss////mmmmyyyylllliiiibbbb....ssssoooo"""",,,, RRRRTTTTLLLLDDDD____LLLLAAAAZZZZYYYY))));;;;
  115.           hhhhaaaannnnddddlllleeee2222 ==== ssssggggiiiiddddllllaaaadddddddd((((""""////uuuussssrrrr////hhhhoooommmmeeee////mmmmeeee////mmmmyyyylllliiiibbbbssss////mmmmyyyylllliiiibbbb....ssssoooo"""",,,, RRRRTTTTLLLLDDDD____LLLLAAAAZZZZYYYY))));;;;
  116.           ............
  117.  
  118.      results in mmmmyyyylllliiiibbbb....ssssoooo being loaded twice for the current process.  On the
  119.      other hand, given the same object and current working directory, if
  120.      LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH====////uuuussssrrrr////hhhhoooommmmeeee////mmmmeeee////mmmmyyyylllliiiibbbbssss, then
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSGGGGIIIIDDDDLLLLAAAADDDDDDDD((((3333CCCC))))                                                      SSSSGGGGIIIIDDDDLLLLAAAADDDDDDDD((((3333CCCC))))
  137.  
  138.  
  139.  
  140.           ............
  141.           vvvvooooiiiidddd ****hhhhaaaannnnddddlllleeee1111;;;;
  142.           vvvvooooiiiidddd ****hhhhaaaannnnddddlllleeee2222;;;;
  143.  
  144.           hhhhaaaannnnddddlllleeee1111 ==== ssssggggiiiiddddllllaaaadddddddd((((""""mmmmyyyylllliiiibbbb....ssssoooo"""",,,, RRRRTTTTLLLLDDDD____LLLLAAAAZZZZYYYY))));;;;
  145.           hhhhaaaannnnddddlllleeee2222 ==== ssssggggiiiiddddllllaaaadddddddd((((""""////uuuussssrrrr////hhhhoooommmmeeee////mmmmeeee////mmmmyyyylllliiiibbbbssss////mmmmyyyylllliiiibbbb....ssssoooo"""",,,, RRRRTTTTLLLLDDDD____LLLLAAAAZZZZYYYY))));;;;
  146.           ............
  147.  
  148.      results in mmmmyyyylllliiiibbbb....ssssoooo being loaded only once.
  149.  
  150. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  151.      ddddllllooooppppeeeennnn(3) ddddlllleeeerrrrrrrroooorrrr(3), ddddllllcccclllloooosssseeee(3), ddddllllssssyyyymmmm(3), ssssggggiiiiddddllllooooppppeeeennnn____vvvveeeerrrrssssiiiioooonnnn(3), rrrrlllldddd(1),
  152.      ddddssssoooo(5).
  153.  
  154. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  155.      If _p_a_t_h_n_a_m_e cannot be found, cannot be opened for reading, is not a
  156.      shared object, or if an error occurs during the process of loading
  157.      _p_a_t_h_n_a_m_e or relocating its symbolic references, ssssggggiiiiddddllllaaaadddddddd returns NNNNUUUULLLLLLLL.
  158.      More detailed diagnostic information is available through ddddlllleeeerrrrrrrroooorrrr.
  159.  
  160. NNNNOOOOTTTTEEEESSSS
  161.      Use of ddddllllcccclllloooosssseeee on a ddddllllaaaadddddddded DSO can cause surprising side effects because
  162.      ddddllllcccclllloooosssseeee forces many symbol's GOT entries to be reset for re-lazy-
  163.      evaluation.  A result of this is that previously-saved (by the
  164.      application or some library) function pointers may hold values that could
  165.      be obsolete or no longer correct.
  166.  
  167.      Symbol lookups proceed in order on a linear list, and a DSO is not opened
  168.      twice with the same version number  (unless different dlopen paths make
  169.      the DSO name appear different to _r_l_d).  When multiple ssssggggiiiiddddllllaaaadddddddds are done
  170.      and an earlier DSO is ddddllllcccclllloooosssseeeed this can change what symbol a call is
  171.      resolved to. See the discussion of this in the ddddllllooooppppeeeennnn description under
  172.      "NAMESPACE ISSUES".
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.